           

#ifndef FUNCAPI_H
#define FUNCAPI_H

#include "access/tupdesc.h"
#include "executor/executor.h"
#include "executor/tuptable.h"
#include "fmgr.h"

/*-------------------------------------------------------------------------
 *	支持简化编写返回复合类型的函数
 *-------------------------------------------------------------------------
 *
 * 这个结构体保存创建元组所需的单个属性信息的数组
 *，来自原始 C 字符串。它还需要
 * TupleDesc 的副本。这里携带的信息
 * 源自 TupleDesc，但存储在这里是为了
 * 避免在每次调用 SRF 时重复使用 CPU 周期。
 */
typedef struct AttInMetadata
{
	/* 完整的 TupleDesc */
	TupleDesc	tupdesc;

	/* 属性类型输入函数 finfo 的数组 */
	FmgrInfo   *attinfuncs;

	/* 属性类型 i/o 参数 OIDs 的数组 */
	Oid		   *attioparams;

	/* 属性 typmod 的数组 */
	int32	   *atttypmods;
} AttInMetadata;

/*-------------------------------------------------------------------------
 *		支持结构以简化编写返回集的函数 (SRFs)
 *-------------------------------------------------------------------------
 *
 * 这个结构体保存返回集函数的上下文。
 * 使用 fn_extra 在调用之间保持指向它的指针
 */
typedef struct FuncCallContext
{
	/* 
	 * 我们之前被调用的次数
	 *
	 * call_cntr 在 SRF_FIRSTCALL_INIT() 中初始化为 0，并且
	 * 每次调用 SRF_RETURN_NEXT() 时都为您增加。
	 */
	uint64		call_cntr;

	/* 
	 * 可选的最大调用次数
	 *
	 * max_calls 仅为方便而设置，设置它是可选的。如果
	 * 不设置，您必须提供其他方式来知道函数何时完成。
	 */
	uint64		max_calls;

	/* 
	 * 可选的指向各种用户提供的上下文信息的指针
	 *
	 * user_fctx 用作指向您自己的结构的指针，以在
	 * 调用之间保留任意上下文信息。
	 */
	void	   *user_fctx;

	/* 
	 * 可选的指向包含属性类型输入元数据的结构的指针
	 *
	 * attinmeta 在返回元组（即复合数据类型）时使用，
	 * 在返回基本数据类型时不使用。只有当您
	 * 打算使用 BuildTupleFromCStrings() 创建返回元组时，才需要它。
	 */
	AttInMetadata *attinmeta;

	/* 
	 * 用于必须在多次调用之间存在的结构的内存上下文
	 *
	 * multi_call_memory_ctx 由 SRF_FIRSTCALL_INIT() 为您设置，并且在
	 * SRF_RETURN_DONE() 中用于清理。它是在
	 * SRF 多次调用中重复使用内存的最合适的内存上下文。
	 */
	MemoryContext multi_call_memory_ctx;

	/* 
	 * 可选的指向包含元组描述的结构的指针
	 *
	 * tuple_desc 在返回元组（即复合数据类型）时使用，
	 * 只有当您将使用 heap_form_tuple() 构建元组时才需要它，
	 * 而不是使用 BuildTupleFromCStrings()。请注意，
	 * 存储在这里的 TupleDesc 指针通常应该先经过
	 * BlessTupleDesc()。
	 */
	TupleDesc	tuple_desc;

} FuncCallContext;

/*----------
 *	支持简化编写返回复合类型函数的工作
 *
 * 外部声明：
 * get_call_result_type:
 *		根据函数调用信息记录，确定其应该返回的数据类型。
 *		如果 resultTypeId 不是 NULL，*resultTypeId
 *		接收实际数据类型 OID（这主要对标量
 *		结果类型有用）。如果 resultTupleDesc 不是 NULL，*resultTupleDesc
 *		接收指向 TupleDesc 的指针，当结果是复合
 *		类型时，或者当它是标量结果或行类型无法
 *		确定时为 NULL。注意：如果需要长时间访问，
 *		tupledesc 应该被复制。
 * get_expr_result_type:
 *		给定一个表达式节点，返回与
 *		get_call_result_type 相同的信息。注意：行类型无法
 *		确定的情况与 get_call_result_type 的情况不同。
 * get_func_result_type:
 *		仅给出函数的 OID，返回与
 *		get_call_result_type 相同的信息。注意：行类型无法
 *		确定的情况与 get_call_result_type 的情况不同。
 *		如果可以使用其他函数，请不要使用此函数。
 *
 * 另请参见 get_expr_result_tupdesc()，这是
 * get_expr_result_type() 的一个方便包装，用于当调用者只关心
 * 可确定行类型的情况时。
 *----------
 */

/* get_call_result_type 和兄弟函数的类型类别 */
typedef enum TypeFuncClass
{
	TYPEFUNC_SCALAR,			/* 标量结果类型 */
	TYPEFUNC_COMPOSITE,			/* 可确定的行类型结果 */
	TYPEFUNC_COMPOSITE_DOMAIN,	/* 领域上的可确定行类型结果 */
	TYPEFUNC_RECORD,			/* 不可确定的行类型结果 */
	TYPEFUNC_OTHER				/* 冒充类型，例如伪类型 */
} TypeFuncClass;

extern TypeFuncClass get_call_result_type(FunctionCallInfo fcinfo,
										  Oid *resultTypeId,
										  TupleDesc *resultTupleDesc);
extern TypeFuncClass get_expr_result_type(Node *expr,
										  Oid *resultTypeId,
										  TupleDesc *resultTupleDesc);
extern TypeFuncClass get_func_result_type(Oid functionId,
										  Oid *resultTypeId,
										  TupleDesc *resultTupleDesc);

extern TupleDesc get_expr_result_tupdesc(Node *expr, bool noError);

extern bool resolve_polymorphic_argtypes(int numargs, Oid *argtypes,
										 char *argmodes,
										 Node *call_expr);

extern int	get_func_arg_info(HeapTuple procTup,
							  Oid **p_argtypes, char ***p_argnames,
							  char **p_argmodes);

extern int	get_func_input_arg_names(Datum proargnames, Datum proargmodes,
									 char ***arg_names);

extern int	get_func_trftypes(HeapTuple procTup, Oid **p_trftypes);
extern char *get_func_result_name(Oid functionId);

extern TupleDesc build_function_result_tupdesc_d(char prokind,
												 Datum proallargtypes,
												 Datum proargmodes,
												 Datum proargnames);
extern TupleDesc build_function_result_tupdesc_t(HeapTuple procTuple);


/*----------
 *	支持简化编写返回复合类型函数的工作
 *
 * 外部声明：
 * TupleDesc BlessTupleDesc(TupleDesc tupdesc) - “祝福”一个完成的元组
 *		描述符，以便可以用于返回正确标记的元组。
 *		如果您直接使用 heap_form_tuple，则需要调用此函数。
 *		不过，TupleDescGetAttInMetadata 会为您处理，因此如果您调用
 *		TupleDescGetAttInMetadata，则不需要调用它。
 * AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc) - 基于给定的
 *		TupleDesc 构建一个 AttInMetadata 结构。AttInMetadata 可以与 C 字符串
 *		一起使用，以生成正确格式的元组。
 * HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values) -
 *		给定用户数据的 C 字符串形式构建一个 HeapTuple。values 是一个 C 字符串数组，
 *		每个返回元组的属性对应一个。
 * Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple) - 将
 *		HeapTupleHeader 转换为 Datum。
 *
 * 宏声明：
 * HeapTupleGetDatum(HeapTuple tuple) - 将 HeapTuple 转换为 Datum。
 *
 * 废弃的例程和宏：
 * TupleDesc RelationNameGetTupleDesc(const char *relname) - 用于获取基于
 *		命名关系的 TupleDesc。
 * TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases) - 用于获取基于
 *		类型 OID 的 TupleDesc。
 * TupleGetDatum(TupleTableSlot *slot, HeapTuple tuple) - 给定元组和槽获取 Datum。
 *----------
 */

#define HeapTupleGetDatum(tuple)		HeapTupleHeaderGetDatum((tuple)->t_data)
/* 以上内容的废弃版本 */
#define TupleGetDatum(_slot, _tuple)	HeapTupleGetDatum(_tuple)

extern TupleDesc RelationNameGetTupleDesc(const char *relname);
extern TupleDesc TypeGetTupleDesc(Oid typeoid, List *colaliases);

/* 来自 execTuples.c */
extern TupleDesc BlessTupleDesc(TupleDesc tupdesc);
extern AttInMetadata *TupleDescGetAttInMetadata(TupleDesc tupdesc);
extern HeapTuple BuildTupleFromCStrings(AttInMetadata *attinmeta, char **values);
extern Datum HeapTupleHeaderGetDatum(HeapTupleHeader tuple);



/*----------
 *		对集合返回函数（SRFs）的支持
 *
 * 使用ValuePerCall模式的SRFs的基本API看起来大致如下：
 *
 * Datum
 * my_Set_Returning_Function(PG_FUNCTION_ARGS)
 * {
 *	FuncCallContext    *funcctx;
 *	Datum				result;
 *	MemoryContext		oldcontext;
 *	<用户定义声明>
 *
 *	if (SRF_IS_FIRSTCALL())
 *	{
 *		funcctx = SRF_FIRSTCALL_INIT();
 *		// 在分配后续调用中使用的东西时切换上下文
 *		oldcontext = MemoryContextSwitchTo(funcctx->multi_call_memory_ctx);
 *		<用户定义代码>
 *		<如果返回复合类型>
 *			<构建TupleDesc，可能还有AttInMetadata>
 *		<结束如果返回复合类型>
 *		<用户定义代码>
 *		// 在分配临时内存时返回到原始上下文
 *		MemoryContextSwitchTo(oldcontext);
 *	}
 *	<用户定义代码>
 *	funcctx = SRF_PERCALL_SETUP();
 *	<用户定义代码>
 *
 *	if (funcctx->call_cntr < funcctx->max_calls)
 *	{
 *		<用户定义代码>
 *		<获取结果Datum>
 *		SRF_RETURN_NEXT(funcctx, result);
 *	}
 *	else
 *		SRF_RETURN_DONE(funcctx);
 * }
 *
 * 注意：使用ValuePerCall模式的SRF不保证会运行完成；例如，带有LIMIT的查询可能会在获取所有行之前停止。因此，不要期望在SRF_RETURN_DONE()之前进行资源清理。您不必担心释放在multi_call_memory_ctx中分配的内存，但在调用之间保持文件描述符或其他非内存资源是一个错误。需要这类资源的SRF不应使用这些宏，而应在单个调用中填充tuplestore，如InitMaterializedSRF()所设置的（参见fmgr/README）。或者，设置回调以在查询关闭时释放资源，使用RegisterExprContextCallback()。
 *
 *----------
 */

/* 来自funcapi.c */

/* InitMaterializedSRF()的标志位 */
#define MAT_SRF_USE_EXPECTED_DESC	0x01	/* 使用expectedDesc作为tupdesc。 */
#define MAT_SRF_BLESS				0x02	/* “祝福”一个元组描述符与
											 * BlessTupleDesc() */
extern void InitMaterializedSRF(FunctionCallInfo fcinfo, bits32 flags);

/* 兼容性声明，适用于v15 */
#define SRF_SINGLE_USE_EXPECTED MAT_SRF_USE_EXPECTED_DESC
#define SRF_SINGLE_BLESS		MAT_SRF_BLESS
extern void SetSingleFuncCall(FunctionCallInfo fcinfo, bits32 flags);

extern FuncCallContext *init_MultiFuncCall(PG_FUNCTION_ARGS);
extern FuncCallContext *per_MultiFuncCall(PG_FUNCTION_ARGS);
extern void end_MultiFuncCall(PG_FUNCTION_ARGS, FuncCallContext *funcctx);

#define SRF_IS_FIRSTCALL() (fcinfo->flinfo->fn_extra == NULL)

#define SRF_FIRSTCALL_INIT() init_MultiFuncCall(fcinfo)

#define SRF_PERCALL_SETUP() per_MultiFuncCall(fcinfo)

#define SRF_RETURN_NEXT(_funcctx, _result) \
	do { \
		ReturnSetInfo	   *rsi; \
		(_funcctx)->call_cntr++; \
		rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
		rsi->isDone = ExprMultipleResult; \
		PG_RETURN_DATUM(_result); \
	} while (0)

#define SRF_RETURN_NEXT_NULL(_funcctx) \
	do { \
		ReturnSetInfo	   *rsi; \
		(_funcctx)->call_cntr++; \
		rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
		rsi->isDone = ExprMultipleResult; \
		PG_RETURN_NULL(); \
	} while (0)

#define  SRF_RETURN_DONE(_funcctx) \
	do { \
		ReturnSetInfo	   *rsi; \
		end_MultiFuncCall(fcinfo, _funcctx); \
		rsi = (ReturnSetInfo *) fcinfo->resultinfo; \
		rsi->isDone = ExprEndResult; \
		PG_RETURN_NULL(); \
	} while (0)

/*----------
 *	支持简化处理 VARIADIC 输入的函数编写
 *----------
 *
 * 此函数提取给定输入函数的一组参数值、类型和 NULL 标记。 返回一组数据：
 * - **values 包含提取的 Datum 值的集合。
 * - **types 每个元素的数据类型 OID。
 * - **nulls 追踪元素是否为 NULL。
 *
 * variadic_start 指示 VARIADIC 参数开始的参数编号。
 * 将 convert_unknown 设置为 true 将强制将具有未知数据类型的参数转换为文本。
 *
 * 返回结果是存储的元素数量，如果是 "VARIADIC NULL"，则返回 -1。
 */
extern int	extract_variadic_args(FunctionCallInfo fcinfo, int variadic_start,
								  bool convert_unknown, Datum **values,
								  Oid **types, bool **nulls);

#endif							/* FUNCAPI_H */
